JCSM Shareware Collection 1996 September

home *** CD-ROM | disk | FTP | other *** search

/ JCSM Shareware Collection 1996 September / JCSM Shareware Collection (JCS Distribution) (September 1996).ISO / prgtools / euphor13.zip / LIBRARY.DOC < prev next >

Wrap

Text File | 1995-05-28 | 78KB | 2,117 lines

Part II - Library Routines 1. Introduction A large number of library routines are provided. Some are built right into the interpreter, ex.exe. Others are written in Euphoria and you must include one of the .e files in euphoria\include to use them. Where this is the case, the appropriate include file is noted in the "Syntax" part of the description. Of course an include file need only be included once in your program. The editor displays in magenta those routines that are built into the interpreter, ex.exe, and require no include file. You can override the definition of these built-in routines by defining your own routine with the same name. You will get a suppressible warning if you do this. To indicate what kind of object may be passed in and returned, the following prefixes are used: x - a general object (atom or sequence) s - a sequence a - an atom i - an integer fn - an integer used as a file number st - a string sequence, or single-character atom An error will result if an illegal argument value is passed to any of these routines. 2. Routines by Application Area 2.1 Predefined Types As well as declaring variables with these types, you can also call them just like ordinary functions, in order to test if a value is a certain type. integer - test if an object is an integer atom - test if an object is an atom sequence - test if an object is a sequence 2.2 Sequence Manipulation length - return the length of a sequence repeat - repeat an object n times to form a sequence of length n append - add a new element to the end of a sequence prepend - add a new element to the beginning of a sequence 2.3 Searching and Sorting compare - compare two objects find - find an object in a sequence match - find a sequence as a slice of another sequence sort - sort the elements of a sequence into ascending order 2.4 Pattern Matching lower - convert a string to lower case upper - convert a string to upper case wildcard_match - match a pattern containing ? and * wildcards wildcard_file - match a file name against a wild card specification 2.5 Math These routines can be applied to individual atoms or to sequences of values. See "Arithmetic Operations on Sequences" in chapter 2 of the reference manual. sqrt - calculate the square root of an object rand - generate random numbers sin - calculate the sine of an angle cos - calculate the cosine of an angle tan - calculate the tangent of an angle log - calculate the natural logarithm floor - round down to the nearest integer remainder - calculate the remainder when a number is divided by another power - calculate a number raised to a power 2.6 File and Device I/O To do input or output on a file or device you must first open the file or device, then use the routines below to read or write to it, then close the file or device. open() will give you a file number to use as the first argument of the other I/O routines. Certain files/devices are opened for you automatically (as text files): 0 - standard input 1 - standard output 2 - standard error Unless you redirect them on the command line, standard input comes from the keyboard, standard output and standard error go to the screen. When you write something to the screen it is written immediately without buffering. If you write to a file, your characters are put into a buffer until there are enough of them to write out efficiently. When you close the file or device, any remaining characters are written out. Input from files is also buffered. When your program terminates, any files that are still open will be closed for you automatically. Note: If a program (written in Euphoria or any other language) has a file open for writing, and you are forced to reboot your computer for any reason, then you should immediately run CHKDSK or SCANDISK to repair any damage to the file system that may have occurred. open - open a file or device close - close a file or device print - print a Euphoria object with {,,} to show the structure ? x - shorthand for print(1, x) printf - formatted print to a file or device sprintf - formatted print returned as a string sequence puts - output a string sequence to a file or device getc - read the next character from a file or device gets - read the next line from a file or device get_key - check for key pressed by the user, don't wait wait_key - wait for user to press a key get - read the representation of any Euphoria object from a file value - read the representation of any Euphoria object from a string seek - move to any character position within an open file where - report the current character position in an open file current_dir - return the name of the current directory dir - return complete info on all files in a directory 2.7 Mouse Support get_mouse - return mouse "events" (clicks, movements) mouse_events - select mouse events to watch for mouse_pointer - display or hide the mouse pointer 2.8 Operating System time - number of seconds since a fixed point in the past date - current year, month, day, hour, minute, second etc. command_line - DOS command-line used to run this program getenv - get value of an environment variable system - execute a DOS command line abort - terminate execution 2.9 Special Machine-dependent routines machine_func - specialized operations in ex.exe with return value machine_proc - specialized operations in ex.exe - no return value 2.10 Debugging trace - dynamically turns tracing on or off 2.11 Graphics & Sound clear_screen - clear the screen - text or graphics position - set cursor line and column get_position - return cursor line and column graphics_mode - select a new graphics (or text) mode video_config - return parameters of current graphics mode scroll - scroll text screen up or down wrap - control line wrap at right edge of screen cursor - select cursor shape text_color - set foreground text color bk_color - set background color for text and graphics palette - change color for one color number all_palette - change color for all color numbers text_rows - set number of lines on text screen pixel - set color of a pixel or set of pixels get_pixel - read color of a pixel or set of pixels draw_line - connect a series of graphics points with a line polygon - draw an n-sided figure ellipse - draw an ellipse (circle) sound - make a sound on the PC speaker read_bitmap - read a bitmap file and return a sequence of pixels save_image - save a rectangular region from a graphics screen save_text_image - save a rectangular region from a text screen display_image - display an image on the graphics screen display_text_image - display an image on the text screen get_active_page - return the page currently being written to set_active_page - change the page currently being written to get_display_page - return the page currently being displayed set_display_page - change the page currently being displayed 2.12 Machine Level Interface With this low-level machine interface you can read and write to memory. You can also set up your own 386+ machine language routines and call them. The usual guarantee that Euphoria will protect you from machine- level errors does *not* apply when you use these routines. There are only some simple checks to catch the use of memory addresses that are negative or zero. (Theoretically address 0 is acceptable, but in practice it is usually an error so we catch it.) If you do happen to reference a bad address, it will likely be caught by DOS4GW and you'll see an error message with a dump of register values. Most Euphoria programmers will never use this interface, but it is important because it makes it possible to get into every nook and cranny of the hardware and operating system. For those with very specialized applications this could be crucial. Machine code routines can be written by hand, or taken from the disassembled output of a compiler for C or some other language. Remember that your machine code will be running in 32-bit protected mode. See demo\callmach.ex for an example. peek - read a byte from memory poke - write a byte to memory call - call a machine language routine allocate - allocate a block of memory free - deallocate a block of memory int_to_bytes - convert an integer to 4 bytes bytes_to_int - convert 4 bytes to an integer int_to_bits - convert an integer to a sequence of bits bits_to_int - convert a sequence of bits to an integer 3. Alphabetical Listing of all Routines ──────────────────────────────────────<?>─────────────────────────────────────── Syntax: ? x Description: This is just a shorthand way of saying: print(1, x) i.e. printing the value of an expression to the standard output. Example: ? {1, 2} + {3, 4} would display {4, 6}. Comments: ? differs slightly from print() since it will add new-lines to make the output more readable on your screen or wherever you have directed standard output. See Also: print ────────────────────────────────────<abort>───────────────────────────────────── Syntax: abort(a) Description: Abort execution of the program. The argument a is an integer status value to be returned to the operating system. A value of 0 generally indicates successful completion of the program. Other values can indicate various kinds of errors. Euphoria for MS-DOS currently ignores this argument and always returns 0. Comments: abort() is useful when a program is many levels deep in subroutine calls, and execution must end immediately, perhaps due to a severe error that has been detected. Example: if x = 0 then puts(ERR, "can't divide by 0 !!!\n") abort(1) else z = y / x end if ─────────────────────────────────<all_palette>────────────────────────────────── Syntax: include graphics.e all_palette(s) Description: Specify new color intensities for the entire set of colors in the current graphics mode. s is a sequence of the form: {{r,g,b}, {r,g,b}, ... {r,g,b}} Each element specifies a new color intensity {red, green, blue} for the corresponding color number, starting with color number 0. The values for red, green and blue must be in the range 0 to 63. Comments: This executes much faster than if you were to use palette() to set the new color intensities one by one. This procedure can be used with read_bitmap() to quickly display a picture on the screen. Example Program: demo\bitmap.ex See Also: palette, read_bitmap, video_config, graphics_mode ───────────────────────────────────<allocate>─────────────────────────────────── Syntax: include machine.e a = allocate(i) Description: Allocate i contiguous bytes of memory. Return the address of the block of memory, or return 0 if the memory can't be allocated. Example: buffer = allocate(100) for i = 0 to 99 do poke(buffer+i, 0) end for See Also: free, peek, poke ────────────────────────────────────<append>──────────────────────────────────── Syntax: s2 = append(s1, x) Description: Create a sequence identical to s1 but with x added on the end as the last element. The length of s2 will be length(s1) + 1. Comments: If x is an atom this is equivalent to s2 = s1 & x. If x is a sequence it is not equivalent. The extra storage is allocated automatically and very efficiently with Euphoria's dynamic storage allocation. The case where s1 and s2 are the same variable (as below) is highly optimized. Example 1: You can use append to dynamically grow a sequence e.g. x = {} for i = 1 to 10 do x = append(x, i) end for -- x is now {1,2,3,4,5,6,7,8,9,10} Example 2: x = {"fred", "barney"} x = append(x, "wilma") -- x is now {"fred", "barney", "wilma"} See Also: prepend, concatenation (&) operator in refman.doc ─────────────────────────────────────<atom>───────────────────────────────────── Syntax: i = atom(x) Description: Return 1 if x is an atom else return 0. Comments: This serves to define the atom type. You can also call it like an ordinary function to determine if an object is an atom. Example 1: atom a a = 5.99 Example 2: line = gets(0) if atom(line) then puts(SCREEN, "end of file\n") end if See Also: sequence ─────────────────────────────────<bits_to_int>────────────────────────────────── Syntax: include machine.e a = bits_to_int(s) Description: Convert a sequence of binary 1's and 0's into a positive number. The least-significant bit is s[1]. Comments: If you print s the bits will appear in "reverse" order, but it is convenient to have increasing subscripts access bits of increasing significance. Example: a = bits_to_int({1,1,1,0,1}) -- a is 23 (binary 10111) See Also: int_to_bits, and/or/not of sequences in refman.doc ───────────────────────────────────<bk_color>─────────────────────────────────── Syntax: include graphics.e bk_color(i) Description: Set the background color. In graphics modes the whole screen is affected immediately. In text modes any new characters that you print will have the new background color. Comments: The various colors are defined as constants in graphics.e Example: bk_color(BLACK) See Also: text_color ─────────────────────────────────────<call>───────────────────────────────────── Syntax: call(a) Description: Call a machine language routine that starts at address a. This routine must execute a RET instruction #C3 to return control to Euphoria. The routine should save and restore any registers that it uses. Comments: You can allocate a block of memory for the routine and then poke in the bytes of machine code. You might allocate other blocks of memory for data and parameters that the machine code can operate on. The addresses of these blocks could be poked into the machine code. Example Program: see demo\callmach.ex See Also: allocate, free, peek, poke ─────────────────────────────────<clear_screen>───────────────────────────────── Syntax: clear_screen() Description: Clear the screen using the current background color (may be set by bk_color()). Comments: This works in all text and graphics modes. See Also: bk_color, graphics_mode ────────────────────────────────────<close>───────────────────────────────────── Syntax: close(fn) Description: Close a file or device and flush out any still-buffered characters. Comments: Any still-open files will be closed automatically when your program terminates. See Also: open ────────────────────────────────<command_line>────────────────────────────────── Syntax: s = command_line() Description: Return a sequence of strings, where each string is a word from the ex command line that started Euphoria. The first word will be the path to the Euphoria executable. The next word is the name of your Euphoria .ex file. After that will come any extra words typed by the user. You can use these words in your program. Comments: Euphoria (ex.exe) does not use any command line options. You can use any options for your own program. Example: -- the user types: ex myprog myfile.dat 12345 cmd = command_line() -- cmd will be: {"C:\EUPHORIA\BIN\EX.EXE", "myprog", "myfile.dat", "12345"} See Also: getenv ───────────────────────────────────<compare>──────────────────────────────────── Syntax: i = compare(x1, x2) Description: Return 0 if objects x1 and x2 are identical, 1 if x1 is greater than x2, -1 if x1 is less than x2. Atoms are considered to be less than sequences. Sequences are compared "alphabetically" starting with the first element until a difference is found. Example 1: x = compare({1,2,{3,{4}},5}, {2-1,1+1,{3,{4}},6-1}) -- identical, x is 0 Example 2: if compare("ABC", "ABCD") < 0 then -- -1 -- will be true: ABC is "less" because it is shorter end if See Also: equals (=) operator in refman.doc ─────────────────────────────────────<cos>────────────────────────────────────── Syntax: x2 = cos(x1) Description: Return the cosine of x1, where x1 is in radians. Comments: This function may be applied to an atom or to all elements of a sequence. Example: x = cos({.5, .6, .7}) -- x is {0.8775826, 0.8253356, 0.7648422} See Also: sin, tan, log, sqrt ─────────────────────────────────<current_dir>────────────────────────────────── Syntax: include file.e s = current_dir() Description: Return the name of the current working directory. Example: sequence s s = current_dir() -- s would have "C:\EUPHORIA\DOC" if you were in that directory See Also: dir, getenv ────────────────────────────────────<cursor>──────────────────────────────────── Syntax: include graphics.e cursor(i) Description: Select a style of cursor. graphics.e contains: global constant NO_CURSOR = 8192, UNDERLINE_CURSOR = 1543, BLOCK_CURSOR = 7, HALF_BLOCK_CURSOR = 1031 Example: cursor(BLOCK_CURSOR) ─────────────────────────────────────<date>───────────────────────────────────── Syntax: s = date() Description: Return a sequence with the following information: { year (since 1900), month (January = 1), day (day of month, starting at 1), hour (0 to 23), minute (0 to 59), second (0 to 59), day of the week (Sunday = 1), day of the year (January 1st = 1) } Example: now = date() -- now has: {95,3,24,23,47,38,6,83} -- i.e. Friday March 24, 1995 at 11:47:38pm, day 83 of the year See Also: time ─────────────────────────────────────<dir>────────────────────────────────────── Syntax: include file.e x = dir(st) Description: Return directory information for the file or directory named by st. If there is no file or directory with this name then -1 is returned. This information is similar to what you would get from the DOS DIR command. A sequence is returned where each element is a sequence that describes one file or subdirectory. If st names a directory you may have entries for "." and "..", just as with the DOS DIR command. If st names a file then x will have just one entry, i.e. length(x) will be 1. Each entry contains the name, attributes and file size as well as the year, month, day, hour, minute and second of the last modification. You can refer to the elements of an entry with the following constants defined in file.e: global constant D_NAME = 1, D_ATTRIBUTES = 2, D_SIZE = 3, D_YEAR = 4, D_MONTH = 5, D_DAY = 6, D_HOUR = 7, D_MINUTE = 8, D_SECOND = 9 The attributes element is a string sequence containing characters chosen from: d - directory r - read only file h - hidden file s - system file v - volume-id entry a - archive file A normal file without special attributes would just have an empty string, "", in this field. Comments: The top level directory, e.g. c:\ does not have "." or ".." entries. This function is often used just to test if a file or directory exists. Example: d = dir(current_dir()) -- d might have: { {".", "d", 0 1994, 1, 18, 9, 30, 02}, {"..", "d", 0 1994, 1, 18, 9, 20, 14}, {"fred", "ra", 2350, 1994, 1, 22, 17, 22, 40}, {"sub", "d" , 0, 1993, 9, 20, 8, 50, 12} } d[3][D_NAME] would be "fred" Example Programs: bin\search.ex, install.ex See Also: wildcard_file ────────────────────────────────<display_image>───────────────────────────────── Syntax: include image.e display_image(s1, s2) Description: Display at point s1 on the screen the 2-d sequence of pixels contained in s2. s1 is a two-element sequence {x, y}. s2 is a sequence of sequences, where each sequence is one horizontal line of pixel colors to be displayed. The first pixel of the first sequence is displayed at s1. It is the top-left pixel. All other pixels appear to the right or below of this point. Comments: s2 might be the result of a previous call to save_image(), or read_bitmap(), or it could be something you have created. You could use save_image/display_image in a graphical user interface, to allow "pop-up" dialog boxes, and drop-down menus to appear and disappear without losing what was previously on the screen. The sequences (rows) of the image do not have to all be the same length. Example: display_image({20,30}, {{1,5,9}, {2,4}, {1,0,1,0,4}, {5,5,5}}) -- displays a small 4-line image at {20,30}, with the pixels appearing in the same relative positions as the layout above would indicate Example Program: see demo\bitmap.ex See Also: save_image, read_bitmap, display_text_image ─────────────────────────────<display_text_image>─────────────────────────────── Syntax: include image.e display_text_image(s1, s2) Description: Display the 2-d sequence of characters and attributes contained in s2 at line s1[1], column s1[2]. s2 is a sequence of sequences, where each sequence is a string of characters and attributes to be displayed. The top-left character is displayed at s1. Other characters appear to the right or below of this position. The attributes indicate the foreground and background color of the preceding character. Comments: s2 would normally be the result of a previous call to save_text_image(), although you could construct it yourself. This routine only works in text modes. You might use save_text_image/display_text_image in a text-mode graphical user interface, to allow "pop-up" dialog boxes, and drop-down menus to appear and disappear without losing what was previously on the screen. The sequences of the text image do not have to all be the same length. Example: clear_screen() display_text_image({1,1}, {{'A', WHITE, 'B', GREEN}, {'C', RED+16*WHITE}, {'D', BLUE}}) -- displays: AB C D in the appropriate colors at the top left corner of the screen See Also: save_text_image, display_image ──────────────────────────────────<draw_line>─────────────────────────────────── Syntax: include graphics.e draw_line(i, s) Description: Draw a line connecting two or more points in s, using color i. Example: draw_line(WHITE, {{100, 100}, {200, 200}, {900, 700}}) This would connect the three points in the sequence using a white line, i.e. a line would be drawn from {100, 100} to {200, 200} and another line would be drawn from {200, 200} to {900, 700}. See Also: polygon, ellipse, pixel ───────────────────────────────────<ellipse>──────────────────────────────────── Syntax: include graphics.e ellipse(i1, i2, s1, s2) Description: Draw an ellipse with color i1. The ellipse will neatly fit inside the rectangle defined by diagonal points s1 {x1, y1} and s2 {x2, y2}. If the rectangle is a square then the ellipse will be a circle. Fill the ellipse when i2 is 1. Don't fill when i2 is 0. Example: ellipse(MAGENTA, 0, {10, 10}, {20, 20}) This would make a magenta colored circle just fitting inside the square: {10, 10}, {10, 20}, {20, 20}, {20, 10}. Example Program: demo\sb.ex See Also: polygon, draw_line ─────────────────────────────────────<find>───────────────────────────────────── Syntax: i = find(x, s) Description: Find x as an element of s. If successful, return the index of the first element of s that matches. If unsuccessful return 0. Example 1: location = find(11, {5, 8, 11, 2, 3}) -- location is set to 3 Example 2: names = {"fred", "rob", "george", "mary", ""} location = find("mary", names) -- location is set to 4 See Also: match, compare ────────────────────────────────────<floor>───────────────────────────────────── Syntax: x2 = floor(x1) Description: Return the greatest integer less than or equal to x1. Comments: This function may be applied to an atom or to all elements of a sequence. Example: y = floor({0.5, -1.6, 9.99, 100}) -- y is {0, -2, 9, 100} See Also: remainder ─────────────────────────────────────<free>───────────────────────────────────── Syntax: include machine.e free(a) Description: Free up a previously allocated block of memory by specifying the address of the start of the block, i.e. the address that was returned by allocate(). Comments: Use free() to recycle blocks of memory during execution. This will reduce the chance of running out of memory or getting into excessive virtual memory swapping to disk. Do not reference a block of memory that has been freed. When your program terminates, all allocated memory will be returned to the system. Example Program: demo\callmach.ex See Also: allocate ─────────────────────────────────────<get>────────────────────────────────────── Syntax: include get.e s = get(fn) Description: Read the next representation of a Euphoria object from file fn, and convert it into the value of that object. s will be a 2-element sequence {error status, value}. Error status values are: GET_SUCCESS -- object was read successfully GET_EOF -- end of file before object was read GET_FAIL -- object is not syntactically correct get() can read arbitrarily complicated Euphoria objects. You could have a long sequence of values in braces and separated by commas, e.g. {23, {49, 57}, 0.5, -1, 99, 'A', "john"}. A single call to get() will read in this entire sequence and return it's value as a result. Each call to get() picks up where the previous call left off. For instance, a series of 5 calls to get() would be needed to read in: 99 5.2 {1,2,3} "Hello" -1 Separate the objects with one or more "whitespace" characters (blank, tab or \n). Comments: The combination of print() and get() can be used to save any Euphoria object to disk and later read it back. This technique could be used to implement a database as one or more large Euphoria sequences stored in disk files. The sequences could be read into memory, updated and then written back to disk after each series of transactions is complete. Example: Suppose your program asks the user to enter a number from the keyboard. If he types 77.5, get(0) would return: {GET_SUCCESS, 77.5} whereas gets(0) would return "77.5\n". Example Program: see demo\mydata.ex. See Also: print, value, gets, getc ───────────────────────────────<get_active_page>──────────────────────────────── Syntax: include image.e i = get_active_page() Description: Some graphics modes on most video cards have multiple pages of memory. This lets you write screen output to one page while displaying a different page. get_active_page() returns the current page number that screen output is being sent to. Comments: The active and display pages are both 0 by default. video_config() will tell you how many pages are available in the current graphics mode. See Also: set_active_page, get_display_page, video_config ───────────────────────────────<get_display_page>─────────────────────────────── Syntax: include image.e i = get_display_page() Description: Some graphics modes on most video cards have multiple pages of memory. This lets you write screen output to one page while displaying another. get_display_page() returns the current page number that is being displayed on the monitor. Comments: The active and display pages are both 0 by default. video_config() will tell you how many pages are available in the current graphics mode. See Also: set_display_page, get_active_page, video_config ───────────────────────────────────<get_key>──────────────────────────────────── Syntax: i = get_key() Description: Return the key that was pressed by the user, without waiting for carriage return. Return -1 if no key was pressed. Special codes are returned for the function keys, arrow keys etc. Comments: DOS can hold a small number of key-hits in its keyboard buffer. get_key will return the next one from the buffer, or -1 if the buffer is empty. See Also: wait_key, getc ──────────────────────────────────<get_mouse>─────────────────────────────────── Syntax: include mouse.e x = get_mouse() Description: Return the last mouse event in the form: {event, x, y} or return -1 if there has not been a mouse event since the last time get_mouse() was called. Constants have been defined in mouse.e for the possible mouse events: global constant MOVE = 1, LEFT_DOWN = 2, LEFT_UP = 4, RIGHT_DOWN = 8, RIGHT_UP = 16, MIDDLE_DOWN = 32, MIDDLE_UP = 64 x and y are the coordinates of the mouse pointer at the time that the event occurred. get_mouse() returns immediately with either a -1 or a mouse event. It does not wait for an event to occur. You must check it frequently enough to avoid missing an event. When the next event occurs, the current event will be lost, if you haven't read it. In practice it is not hard to catch almost all events, and the ones that are lost are usually lost at a lower level in the system, beyond the control of your program. Losing a MOVE event is generally not too serious, as the next MOVE will tell you where the mouse pointer is. Comments: You need a DOS mouse driver to use this routine. You can use get_mouse() in most text and graphics modes. Unfortunately, DOS does not support the use of a mouse in SVGA graphics modes (beyond 640x480 pixels). Example: a return value of: {2, 100, 50} would indicate that the left button was pressed down while the mouse pointer was at position x=100, y=50 on the screen. See Also: mouse_events, mouse_pointer ──────────────────────────────────<get_pixel>─────────────────────────────────── Syntax: include graphics.e x = get_pixel(s) Description: When s is a 2-element screen coordinate {x, y}, get_pixel() returns the color of the pixel on the screen at that point. When s is a 3-element sequence of the form: {x, y, n} get_pixel() returns a sequence of n color values for the points starting at {x,y} and moving to the right {x+1,y}, {x+2,y} etc. Points off the screen have unpredictable color values. Comments: When n is specified, a very fast algorithm is used to read the pixel colors on the screen. It is much faster to call pixel() once specifying a large value of n, than it is to call it many times, reading one pixel color at a time. Example: object x x = get_pixel({30,40}) -- x is set to the color value of point x=30, y=40 x = get_pixel({30,40,100}) -- x is set to a sequence of 100 integer values, representing -- the colors starting at {30,40} and going to the right See Also: pixel, graphics_mode, get_position ─────────────────────────────────<get_position>───────────────────────────────── Syntax: include graphics.e s = get_position() Description: Return the current line and column position of the cursor as a 2-element sequence {line, column}. See Also: position, get_pixel ─────────────────────────────────────<getc>───────────────────────────────────── Syntax: i = getc(fn) Description: Get the next character (byte) from file fn. -1 is returned at end of file. Comments: File input using getc is buffered, i.e. getc does not actually go out to the disk for each character. Instead, a large block of characters will be read in at one time and returned to you one by one from a memory buffer. See Also: gets, get_key, wait_key, open ────────────────────────────────────<getenv>──────────────────────────────────── Syntax: x = getenv(s) Description: Return the value of a DOS environment variable. If the variable is undefined return -1. Example: e = getenv("EUDIR") -- e will be "C:\EUPHORIA" -- or perhaps D:, E: etc. Comments: Because either a sequence or an atom (-1) might be returned, you will probably want to assign the result to a variable declared as object. See Also: command_line ─────────────────────────────────────<gets>───────────────────────────────────── Syntax: x = gets(fn) Description: Get the next sequence (one line, including \n) of characters from file fn. The atom -1 is returned on end of file. Comments: Because either a sequence or an atom (-1) might be returned, you will probably want to assign the result to a variable declared as object. Example: sequence buffer object line -- read a text file into a sequence buffer = {} while 1 do line = gets(0) if atom(line) then exit -- end of file end if buffer = append(buffer, line) end while See Also: getc, puts, open ────────────────────────────────<graphics_mode>───────────────────────────────── Syntax: include graphics.e i1 = graphics_mode(i2) Description: Select graphics mode i2. See graphics.e for a list of valid graphics modes. If successful, i1 is set to 0, otherwise i1 is set to 1. Example: if graphics_mode(18) then puts(SCREEN, "need VGA graphics!\n") abort(1) end if draw_line(BLUE, {{0,0}, {50,50}}) See Also: text_rows, video_config ─────────────────────────────────<int_to_bits>────────────────────────────────── Syntax: include machine.e s = int_to_bits(a, i) Description: Returns the low-order i bits of a, as a sequence of 1's and 0's. The least significant bits come first. For negative numbers the two's complement bit pattern is returned. Comments: You can use subscripting, slicing, and/or/not of entire sequences etc. to manipulate sequences of bits. Shifting of bits and rotating of bits are easy to perform. Example: s = int_to_bits(177, 8) -- s is {1,0,0,0,1,1,0,1} -- "reverse" order See Also: bits_to_int, and/or/not of entire sequences in refman.doc ─────────────────────────────────<int_to_bytes>───────────────────────────────── Syntax: include machine.e s = int_to_bytes(a) Description: Convert an integer into a sequence of 4 bytes. These bytes are in the order expected on the 386+, i.e. least significant byte first. Comments: You might use this routine prior to poking the 4 bytes into memory for use by a machine language program. The integer can be negative. Negative byte-values will be returned, but after poking them into memory you will have the correct (two's complement) representation for the 386+. Example 1: s = int_to_bytes(999) -- s is {231, 3, 0, 0} Example 2: s = int_to_bytes(-999) -- s is {-231, -4, -1, -1} See Also: bytes_to_int, int_to_bits, bits_to_int, peek, poke ───────────────────────────────────<integer>──────────────────────────────────── Syntax: i = integer(x) Description: Return 1 if x is an integer in the range -1073741824 to +1073741823. Otherwise return 0. Comments: This serves to define the integer type. You can also call it like an ordinary function to determine if an object is an integer. Example 1: integer z z = -1 Example 2: if integer(y/x) then puts(SCREEN, "y is an exact multiple of x") end if See Also: atom, sequence, floor ────────────────────────────────────<length>──────────────────────────────────── Syntax: i = length(s) Description: Return the length of s. s must be a sequence. An error will occur if s is an atom. Comments: The length of each sequence is stored internally by the interpreter for quick access. (In other languages this operation requires a search through memory for an end marker.) Example 1: length({{1,2}, {3,4}, {5,6}}) -- 3 Example 2: length("") -- 0 Example 3: length({}) -- 0 ─────────────────────────────────────<log>────────────────────────────────────── Syntax: x2 = log(x1) Description: Return the natural logarithm of x1. Comments: This function may be applied to an atom or to all elements of a sequence. Note that log is only defined for positive numbers. Example: a = log(100) -- a is 4.60517 See Also: sin, cos, tan, sqrt ────────────────────────────────────<lower>───────────────────────────────────── Syntax: include wildcard.e s2 = lower(s1) Description: Convert a string of characters to lower case. Example: s = lower("Euphoria") -- s is "euphoria" See Also: upper ─────────────────────────────────<machine_func>───────────────────────────────── Syntax: x = machine_func(a, x) Description: see machine_proc() below ─────────────────────────────────<machine_proc>───────────────────────────────── Syntax: machine_proc(a, x) Description: Perform a machine-specific operation such as graphics and sound effects. This routine should normally be called indirectly via one of the library routines in a Euphoria include file. A direct call can cause a machine exception if done incorrectly. Comments: The only reason that you might want to call machine_proc or machine_func directly would be to increase the speed of your program slightly, by eliminating a layer of subroutine call overhead. See Also: machine_func ────────────────────────────────────<match>───────────────────────────────────── Syntax: i = match(s1, s2) Description: Try to match s1 against some slice of s2. If successful, return the element number of s2 where the (first) matching slice begins, else return 0. Example: location = match("pho", "Euphoria") -- location is set to 3 See Also: find, compare, wildcard_match ─────────────────────────────────<mouse_events>───────────────────────────────── Syntax: include mouse.e mouse_events(i) Description: Use this procedure to select the mouse events that you want get_mouse() to report. By default, get_mouse() will report all events. mouse_events() can be called at various stages of the execution of your program, as the need to detect events changes. Comments: It is good practice to ignore events that you are not interested in, particularly the very frequent MOVE event, in order to reduce the chance that you will miss a significant event. Example: mouse_events(LEFT_DOWN + LEFT_UP + RIGHT_DOWN) -- will restrict get_mouse() to reporting the left button being pressed down or released, and the right button being pressed down. All other events will be ignored. See Also: get_mouse, mouse_pointer ────────────────────────────────<mouse_pointer>───────────────────────────────── Syntax: include mouse.e mouse_pointer(i) Description: If i is 0 hide the mouse pointer, otherwise turn on the mouse pointer. Multiple calls to hide the pointer will require multiple calls to turn it back on. The first call to either get_mouse() or mouse_events() above, will also turn the pointer on (once). Comments: It may be necessary to hide the mouse pointer temporarily when you update the screen. See Also: get_mouse, mouse_events ─────────────────────────────────────<open>───────────────────────────────────── Syntax: fn = open(s1, s2) Description: Open a file or device, to get the file number. -1 is returned if the open fails. s1 is the path name of the file or device. s2 is the mode in which the file is to be opened. Possible modes are: "r" - open text file for reading "rb" - open binary file for reading "w" - create text file for writing "wb" - create binary file for writing "u" - open text file for update (reading and writing) "ub" - open binary file for update "a" - open text file for appending "ab" - open binary file for appending Files opened for read or update must already exist. Files opened for write or append will be created if necessary. A file opened for write will be set to 0 bytes. Output to a file opened for append will start at the end of file. Output to text files will have carriage-return characters automatically added before linefeed characters. On input, these carriage-return characters are removed. A control-Z character (ASCII 26) will signal an immediate end of file. I/O to binary files is not modified in any way. Any byte values from 0 to 255 can be read or written. Some typical devices that you can open are: "CON" the console (screen) "AUX" the serial auxiliary port "COM1" serial port 1 "COM2" serial port 2 "PRN" the printer on the parallel port "NUL" a non-existent device that accepts and discards output Example: integer file_num sequence first_line constant ERROR = 2 file_num = open("myfile", "r") if file_num = -1 then puts(ERROR, "couldn't open myfile\n") else first_line = gets(file_num) end if See Also: close ───────────────────────────────────<palette>──────────────────────────────────── Syntax: include graphics.e x = palette(i, s) Description: Change the color for color number i to s, where s is a sequence of color intensities: {red, green, blue}. Each value in s can be from 0 to 63. If successful, a 3-element sequence containing the previous color for i will be returned, and all pixels on the screen with value i will be set to the new color. If unsuccessful, the atom -1 will be returned. Example: x = palette(0, {15, 40, 10}) -- color number 0 (normally black) is changed to a shade of mainly green. See Also: all_palette ─────────────────────────────────────<peek>───────────────────────────────────── Syntax: i = peek(a) Description: Read a single byte value in the range 0 to 255 from machine address a. Comment: Addresses can sometimes be larger than the largest value of type integer. Variables that hold an address should be declared as atoms. See Also: poke, allocate, free, call ────────────────────────────────────<pixel>───────────────────────────────────── Syntax: include graphics.e pixel(x, s) Description: Set one or more pixels starting at point s, where s is a 2-element screen coordinate {x, y}. If x is an atom, one pixel will be set to the color indicated by x. If x is a sequence then a number of pixels will be set, starting at s and moving to the right (increasing x value, same y value). Comments: When x is a sequence, a very fast algorithm is used to put the pixels on the screen. It is much faster to call pixel() once with a sequence of pixel colors, than it is to call it many times, plotting one pixel color at a time. Example 1: pixel(BLUE, {50, 60}) -- the point {50,60} is set to the color BLUE Example 2: pixel({BLUE, GREEN, WHITE, RED}, {50,60}) -- {50,60} set to BLUE -- {51,60} set to GREEN -- {52,60} set to WHITE -- {53,60} set to RED See Also: get_pixel, graphics_mode ─────────────────────────────────────<poke>───────────────────────────────────── Syntax: poke(a, i) Description: Write a single byte value, i, to memory address a. The lower 8-bits of i are actually stored. Comments: Writing to the screen memory with poke() can be much faster than using puts() or printf(), but the programming is more difficult and less portable. In most cases the speed is not needed. For example, the Euphoria editor never uses poke(). See Also: peek, allocate, free, call ───────────────────────────────────<polygon>──────────────────────────────────── Syntax: include graphics.e polygon(i1, i2, s) Description: Draw a polygon with 3 or more vertices given in s, using a certain color i1. Fill the area if i2 is 1. Don't fill if i2 is 0. Example: polygon(GREEN, 1, {{100, 100}, {200, 200}, {900, 700}}) -- makes a solid green triangle. See Also: draw_line, ellipse ───────────────────────────────────<position>─────────────────────────────────── Syntax: position(a1, a2) Description: Set the cursor to line a1, column a2, where the top left corner is position(1,1). An error will occur if this location is off the screen. Comments: The coordinate system for text is different from the one for graphics. In graphics modes the top-left is (0,0) and the first coordinate controls the horizontal location. Example: position(2,1) -- the cursor moves to the beginning of the second line from the top of the screen See Also: get_position, puts, print, printf ────────────────────────────────────<power>───────────────────────────────────── Syntax: x3 = power(x1, x2) Description: Raise x1 to the power x2 Comments: Powers of 2 are calculated very efficiently. Example: ? power({5, 4, 3.5}, {2, 1, -0.5}) -- {25, 4, 0.534522} is printed See Also: log, sqrt ───────────────────────────────────<prepend>──────────────────────────────────── Syntax: s2 = prepend(s1, x) Description: Prepend x to the start of sequence s1. The length of s2 will be length(s1) + 1. Comments: If x is an atom this is the same as s2 = x & s1. If x is a sequence it is definitely not the same. e.g. prepend({1,2,3}, {0,0}) -- {{0,0}, 1, 2, 3} {0,0} & {1,2,3} -- {0, 0, 1, 2, 3} The case where s1 and s2 are the same variable is handled very efficiently. Example: s = {} for i = 1 to 10 do s = prepend(s, i) end for -- s is {10,9,8,7,6,5,4,3,2,1} See Also: append, concatenation operator (&) in refman.doc ────────────────────────────────────<print>───────────────────────────────────── Syntax: print(fn, x) Description: Print an object x with braces { , , , } to show the structure. Comment: If you want to see a string of characters, rather than just the ASCII codes, you need to use puts or printf. Example: print(1, "ABC") -- output is: {65, 66, 67} puts(1, "ABC") -- output is: ABC See Also: ?, puts, printf, get ────────────────────────────────────<printf>──────────────────────────────────── Syntax: printf(fn, st, x) Description: Print x using format string st. If x is an atom then a single value will be printed. If x is a sequence, then formats from st are applied to successive elements of x. Thus printf always takes exactly 3 arguments. Only the length of the last argument, containing the values to be printed, will vary. The basic formats are: %d - print an atom as a decimal integer %x - print an atom as a hexadecimal integer %o - print an atom as an octal integer %s - print a sequence as a string of characters %e - print an atom as a floating point number with exponential notation %f - print an atom as a floating-point number with a decimal point but no exponent %g - print an atom as a floating point number using either the %f or %e format, whichever seems more appropriate %% - print the '%' character itself Field widths can be added to the basic formats, e.g. %5d, or %8.2f. The number before the decimal point is the minimum field width to be used. The number after the decimal point is the precision to be used. If the field width is negative, e.g. %-5d then the value will be left-justified within the field. Normally it will be right- justified. If the field width starts with a leading 0, e.g. %08d then leading zeros will be supplied to fill up the field. If the field width starts with a '+' e.g. %+7d then a plus sign will be printed for positive values. Example 1: rate = 7.875 printf(myfile, "The interest rate is: %8.2f\n", rate) The interest rate is: 7.88 Example 2: name="John Smith" score=97 printf(1, "%15s, %5d\n", {name, score}) John Smith, 97 Comments: Watch out for the following common mistake: printf(1, "%15s", name) This will print only the first character of name, as each element of name is taken to be a separate value to be formatted. You must say this instead: printf(1, "%15s", {name}) See Also: sprintf, puts, open ─────────────────────────────────────<puts>───────────────────────────────────── Syntax: puts(fn, x) Description: Output a single character (atom) or sequence of characters as bytes of text. Example 1: puts(SCREEN, "Enter your first name: ") Example 2: puts(output, 'A') -- the single byte 65 will be sent to output See Also: printf, gets, open ─────────────────────────────────────<rand>───────────────────────────────────── Syntax: x2 = rand(x1) Description: Return a random integer from 1 to x1, where x1 may be from 1 to the largest positive value of type integer (1073741823). Comments: This function may be applied to an atom or to all elements of a sequence. Example: s = rand({10, 20, 30}) -- s might be: {5, 17, 23} or {9, 3, 12} etc. ─────────────────────────────────<read_bitmap>────────────────────────────────── Syntax: include image.e x = read_bitmap(st) Description: st is the name of a .bmp "bitmap" file. The file should be in the bitmap format. The most common variations of the format are supported. If the file is read successfully the result will be a 2-element sequence. The first element is the palette. The second element is a 2-d sequence of sequences containing a graphics-mode image. You can pass the palette to all_palette() (after dividing it by 4 to scale it). The image can be passed to display_image(). Bitmaps of 2,4,16 or 256 colors are supported. If the file is not in a good format an error code (atom) is returned instead: global constant BMP_OPEN_FAILED = 1, BMP_UNEXPECTED_EOF = 2, BMP_UNSUPPORTED_FORMAT = 3 Comments: You can create your own bitmap picture files using the Windows Paintbrush program. You can then incorporate these pictures into your programs. Example: x = read_bitmap("c:\\windows\\arcade.bmp") -- note: double backslash needed to get single backslash in a string Example Program: demo\bitmap.ex See Also: palette, display_image ──────────────────────────────────<remainder>─────────────────────────────────── Syntax: x3 = remainder(x1, x2) Description: Compute the remainder after dividing x1 by x2. The result will have the same sign as x1, and the magnitude of the result will be less than the magnitude of x2. Example 1: s = remainder({81, -3.5, -9, 5.5}, {8, -1.7, 2, -4}) -- s is {1, -0.1, -1, 1.5} Example 2: s = remainder({17, 12, 34}, 16) -- s is {1, 12, 2} ────────────────────────────────────<repeat>──────────────────────────────────── Syntax: s = repeat(x, a) Description: Create a sequence of length a where each element is x. Comments: When you repeat a sequence or a floating-point number the interpreter does not actually make multiple copies in memory. Rather, a single copy is "pointed to" a number of times. Example 1: repeat(0, 10) -- {0,0,0,0,0,0,0,0,0,0} Example 2: repeat("JOHN", 4) -- {"JOHN", "JOHN", "JOHN", "JOHN"} See Also: append, prepend ──────────────────────────────────<save_image>────────────────────────────────── Syntax: include image.e s3 = save_image(s1, s2) Description: Save a rectangular image from a graphics screen. The result is a 2-d sequence of sequences containing all the pixels in the image. You can redisplay the image using display_image(). s1 is a 2-element sequence {x1, y1} specifying the top-left pixel in the image. s2 is a sequence {x2, y2} specifying the bottom-right pixel. Comments: You might use this in a graphical user interface to save a portion of the screen before you display a drop-down menu or dialog box. Example: s = save_image({0,0}, {50,50}) display_image({100,200}, s) display_image({300,400}, s) -- saves a 51x51 square image, then redisplays it at {100,200} -- and at {300,400} See Also: display_image, save_text_image ───────────────────────────────<save_text_image>──────────────────────────────── Syntax: include image.e s3 = save_text_image(s1, s2) Description: Save a rectangular region of text from a text-mode screen. The result is a sequence of sequences containing ASCII characters and attributes from the screen. You can redisplay this text using display_text_image(). s1 is a 2-element sequence {line1, column1} specifying the top-left character. s2 is a sequence {line2, column2} specifying the bottom right character. Comments: Because the character attributes are also saved, you will get the correct foreground and background color for each character if you redisplay the text. This routine only works in text modes. You might use this function in a text-mode graphical user interface to save a portion of the screen before displaying a drop-down menu, dialog box, alert box etc. If you are flipping video pages, note that this function reads from the current active page. Example: If the top 2 lines of the screen have: Hello World s = save_text_image({1,1,}, {2, 5}) Then s is something like: {"H-e-l-l-o-", W-o-r-l-d-"} where we have indicated the attribute bytes by '-' See Also: display_text_image, save_image, set_active_page ────────────────────────────────────<scroll>──────────────────────────────────── Syntax: include graphics.e scroll(i1, i2, i3) Description: Scroll a region of text on the screen either up (i1 positive) or down (i1 negative) by i1 lines. The region is the series of lines on the screen from i2 (top line) to i3 (bottom line), inclusive. A new blank line will appear at the top or bottom. Example Program: see bin\ed.ex See Also: clear_screen, text_rows ─────────────────────────────────────<seek>───────────────────────────────────── Syntax: include file.e i1 = seek(fn, i2) Description: Seek (move) to any byte position in the file fn or to the end of file if i2 is -1. For each open file there is a current byte position that is updated as a result of I/O operations on the file. The initial file position is 0 for files opened for read, write or update. The initial position is the end of file for files opened for append. The value returned by seek() is 0 if the seek was successful, and non-zero if it was unsuccessful. It is possible to seek past the end of a file. In this case undefined bytes will be added to the file to make it long enough for the seek. See Also: where, open ───────────────────────────────<set_active_page>──────────────────────────────── Syntax: include image.e set_active_page(i) Description: Select video page i to send all screen output to. Comments: With multiple pages you can instantaneously change the entire screen without causing any visible "flicker". You can also save the screen and bring it back quickly. video_config() will tell you how many pages are available in the current graphics mode. By default, the active page and the display page are both 0. This works under DOS, or full-screen under Windows. In a partial-screen window you cannot change the active page. Example: include image.e -- active & display pages are initially both 0 puts(1, "\nThis is page 0\n") set_active_page(1) -- screen output will now go to page 1 clear_screen() puts(1, "\nNow we've flipped to page 1\n") if getc(0) then -- wait for key-press end if set_display_page(1) -- "Now we've ..." becomes visible if getc(0) then -- wait for key-press end if set_display_page(0) -- "This is ..." becomes visible again set_active_page(0) See Also: get_active_page, set_display_page ──────────────────────────────<set_display_page>──────────────────────────────── Syntax: include image.e set_display_page(i) Description: Set video page i to be mapped to the visible screen. Comments: With multiple pages you can instantaneously change the entire screen without causing any visible "flicker". You can also save the screen and bring it back quickly. video_config() will tell you how many pages are available in the current graphics mode. By default, the active page and the display page are both 0. This works under DOS, or full-screen under Windows. In a partial-screen window you cannot change the active page. Example: See set_active_page example. See Also: get_display_page, set_active_page ───────────────────────────────────<sequence>─────────────────────────────────── Syntax: i = sequence(x) Description: Return 1 if x is a sequence else return 0. Comments: This serves to define the sequence type. You can also call it like an ordinary function to determine if an object is a sequence. Example 1: sequence s s = {1,2,3} Example 2: if sequence(x) then sum = 0 for i = 1 to length(x) do sum = sum + x[i] end for else -- x must be an atom sum = x end if See Also: atom, object type in refman.doc ─────────────────────────────────────<sin>────────────────────────────────────── Syntax: x2 = sin(x1) Description: Return the sine of x1, where x1 is in radians. Comments: This function may be applied to an atom or to all elements of a sequence. Example: sin_x = sin({.5, .9, .11}) -- sin_x is {.479, .783, .110} See Also: cos, tan ─────────────────────────────────────<sort>───────────────────────────────────── Syntax: include sort.e x2 = sort(x1) Description: Sort x into ascending order using a fast sorting algorithm. By defining your own compare function to override the built-in compare(), you can change the ordering of values from sort(), and perhaps choose a field or element number on which to base the sort. Define your compare() as a global function before including sort.e. Example: x = 0 & sort({7,5,3,8}) & 0 -- x is set to {0, 3, 5, 7, 8, 0} See Also: compare, match, find ────────────────────────────────────<sound>───────────────────────────────────── Syntax: sound(i) Description: Turn on the PC speaker at frequency i. If i is 0 the speaker will be turned off. Example: sound(1000) -- starts a fairly high pitched sound ───────────────────────────────────<sprintf>──────────────────────────────────── Syntax: s = sprintf(st, x) Description: This is exactly the same as printf(), except that the output is returned as a sequence of characters, rather than being sent to a file or device. st is a format string, x is the value or sequence of values to be formatted. printf(fn, st, x) is equivalent to puts(fn, sprintf(st, x)). Comments: Some typical uses of sprintf are: 1. Converting numbers to strings. 2. Creating strings to pass to system(). 3. Creating formatted error messages and passing them to a common error message handler. Example: s = sprintf("%08d", 12345) -- s is "00012345" See Also: printf, value, get ─────────────────────────────────────<sqrt>───────────────────────────────────── Syntax: x2 = sqrt(x1) Description: Calculate the square root of x1. Comments: This function may be applied to an atom or to all elements of a sequence. Example: r = sqrt(16) -- r is 4 See Also: log, power ────────────────────────────────────<system>──────────────────────────────────── Syntax: system(s, a) Description: Pass a command string s to the DOS command interpreter for execution. The argument a indicates the manner in which to return from the system call. value of a return action ---------- ------------- 0 - restore previous graphics mode (clears the screen) 1 - make a beep sound, wait for a key press, then restore the graphics mode 2 - do not restore graphics mode Comments: Action 2 should only be used when it is known that the system call will not change the graphics mode. You can use Euphoria as a sophisticated DOS "batch" language by making calls to system(). Example: system("copy temp.txt a:\\temp.bak", 2) -- note use of double backslash in literal string to get single backslash Example Program: see install.ex See Also: dir, current_dir, getenv, command_line ─────────────────────────────────────<tan>────────────────────────────────────── Syntax: x2 = tan(x1) Description: Return the tangent of x1, where x1 is in radians. Comments: This function may be applied to an atom or to all elements of a sequence. Example: t = tan(1.0) -- t is 1.55741 See Also: sin, cos ──────────────────────────────────<text_color>────────────────────────────────── Syntax: include graphics.e text_color(i) Description: Set the foreground text color. Add 16 to get blinking text in some modes. See graphics.e for a list of possible colors. Example: text_color(BRIGHT_BLUE) See Also: bk_color ──────────────────────────────────<text_rows>─────────────────────────────────── Syntax: include graphics.e i2 = text_rows(i1) Description: Set the number of lines of text on the screen to i1 if possible. i2 will be set to the actual new number of lines. Comments: Values of 25, 28, 43 and 50 lines are supported by most graphics cards. See Also: graphics_mode ─────────────────────────────────────<time>───────────────────────────────────── Syntax: a = time() Description: Return the number of seconds since some fixed point in the past. The resolution on MS-DOS is about 0.05 seconds. Comments: Take the difference between two readings of time(), to measure, for example, how long a section of code takes to execute. Example: constant ITERATIONS = 1000000 integer p atom t0, loop_overhead t0 = time() for i = 1 to ITERATIONS do end for loop_overhead = time() - t0 t0 = time() for i = 1 to ITERATIONS do p = power(2, 20) end for ? (time() - t0 - loop_overhead)/ITERATIONS -- calculates time (in seconds) for one call to power See Also: date ────────────────────────────────────<trace>───────────────────────────────────── Syntax: with trace trace(x) Description: If x is 1 or 2 then turn on full-screen statement tracing. If x is 0 then turn off tracing. When x is 2 a monochrome trace display is forced on. Tracing only occurs in subroutines that were compiled "with trace". See the section on Debugging in refman.doc. Comments: Use trace(2) if the color display is hard to view on your system. Example: if x < 0 then -- ok, here's the case I want to debug... trace(1) -- etc. ... end if See Also: Chapter 3 in refman.doc. ────────────────────────────────────<upper>───────────────────────────────────── Syntax: include wildcard.e s2 = upper(s1) Description: Convert a string of characters to upper case. Example: s = upper("Euphoria") -- s is "EUPHORIA" See Also: lower ────────────────────────────────────<value>───────────────────────────────────── Syntax: include get.e s = value(st) Description: Read the string representation of a Euphoria object, and compute the value of that object. A 2-element sequence, {error_status, value} is actually returned, where error_status can be one of: GET_SUCCESS -- a valid object representation was found GET_EOF -- end of string reached too soon GET_FAIL -- syntax is wrong Comments: This works the same as get(), but it reads from a string that you supply, rather than from a file or device. Example 1: s = value("12345"} -- s is {GET_SUCCESS, 12345} Example 2: s = value("{0, 1, -99.9}") -- s is {GET_SUCCESS, {0, 1, -99.9}} Example 3: s = value("+++") -- s is {GET_FAIL, 0} See Also: get, sprintf, print ─────────────────────────────────<video_config>───────────────────────────────── Syntax: include graphics.e s = video_config() Description: Return a sequence of values describing the current video configuration: {color monitor?, graphics mode, text rows, text columns, xpixels, ypixels, number of colors, number of pages} The following constants are defined in graphics.e: global constant VC_COLOR = 1, VC_MODE = 2, VC_LINES = 3, VC_COLUMNS = 4, VC_XPIXELS = 5, VC_YPIXELS = 6, VC_NCOLORS = 7, VC_PAGES = 8 Comments: This routine makes it easy for you to parameterize a program so it will work in many different graphics modes. Example: vc = video_config() -- in mode 3 with 25-lines of text: -- vc is {1, 3, 25, 80, 0, 0, 32, 8} ──────────────────────────────────<wait_key>──────────────────────────────────── Syntax: include get.e i = wait_key() Description: Return the next key pressed by the user. Don't return until a key is pressed. Comments: You could achieve the same result using get_key() as follows: while 1 do k = get_key() if k != -1 then exit end if end while However, on multi-tasking systems like Windows, Windows NT, or OS/2 this "busy waiting" would slow the system down. wait_key() lets the operating system do other useful work while your program is waiting for the user to press a key. You could also use getc(0), assuming file number 0 was input from the keyboard, except that you wouldn't pick up the special codes for function keys, arrow keys etc. See Also: get_key, getc ────────────────────────────────────<where>───────────────────────────────────── Syntax: include file.e i = where(fn) Description: This function returns the current byte position in the file fn. This position is updated by reads, writes and seeks on the file. It is the place in the file where the next byte will be read from, or written to. See Also: seek, open ────────────────────────────────<wildcard_file>───────────────────────────────── Syntax: include wildcard.e i = wildcard_file(s1, s2) Description: Return 1 (TRUE) if the filename s2 matches the wild card pattern s1. Return 0 (FALSE) otherwise. This is similar to DOS wildcard matching, but better in some cases. * matches any 0 or more characters, ? matches any single character. Character comparisons are not case sensitive. Comments: You might use this function to check the output of the dir() routine for file names that match a pattern supplied by the user of your program. In DOS "*ABC.*" will match ALL files. wildcard_file("*ABC.*", s) will only match when the file name part has "ABC" at the end (as you would expect). Example 1: i = wildcard_file("AB*CD.?", "aB123cD.e") -- i is set to 1 Example 2: i = wildcard_file("AB*CD.?", "abcd.ex") -- i is set to 0, because the file type has 2 letters not 1 Example Program: see bin\search.ex See Also: wildcard_match, dir ────────────────────────────────<wildcard_match>──────────────────────────────── Syntax: include wildcard.e i = wildcard_match(s1, s2) Description: This function performs general matching of a string against a pattern containing * and ? wildcards. It returns 1 (TRUE) if string s2 matches pattern s1. It returns 0 (FALSE) otherwise. * matches any 0 or more characters. ? matches any single character. Character comparisons are case sensitive. Comments: If you want case insensitive comparisons, pass both s1 and s2 through upper(), or both through lower() before calling wildcard_match(). If you want to detect a pattern anywhere within a string, add * to each end of the pattern: i = wildcard_match('*' & pattern & '*', string) There is currently no way to treat * or ? literally in a pattern. Example 1: i = wildcard_match("A?B*", "AQBXXYY") -- i is 1 (TRUE) Example 2: i = wildcard_match("*xyz*", "AAAbbbxyz") -- i is 1 (TRUE) Example 3: i = wildcard_match("A*B*C", "a111b222c") -- i is 0 (FALSE) because upper/lower case doesn't match Example Program: see bin\search.ex See Also: wildcard_file, match, upper, lower, compare ─────────────────────────────────────<wrap>───────────────────────────────────── Syntax: include graphics.e wrap(i) Description: Allow text to wrap at the right margin (i = 1) or get truncated (i = 0). Comments: By default text will wrap. Example: puts(1, repeat('x', 100) & "\n\n") -- now have a line of 80 'x' followed a line of 20 more 'x' wrap(0) puts(1, repeat('x', 100) & "\n\n") -- creates just one line of 80 'x' See Also: puts, position